home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 July: Mac OS SDK / Dev.CD Jul 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Interfaces / CIncludes / NetSprocket.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-09-11  |  13.4 KB  |  564 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        NetSprocket.h
  3.  
  4.      Contains:    Public interfaces for NetSprocket
  5.  
  6.      Version:    Technology:    Apple Game Sprockets 1.0
  7.                  Package:    Universal Interfaces 2.1.4
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.
  10.                  All rights reserved.
  11.  
  12.      Bugs?:        If you find a problem with this file, use the Apple Bug Reporter
  13.                  stack.  Include the file and version information (from above)
  14.                  in the problem description and send to:
  15.                      Internet:    apple.bugs@applelink.apple.com
  16.                      AppleLink:    APPLE.BUGS
  17. */
  18.  
  19. #ifndef __NETSPROCKET__
  20. #define __NETSPROCKET__
  21.  
  22. #ifndef __TYPES__
  23. #include <Types.h>
  24. #endif
  25.  
  26. #ifndef __EVENTS__
  27. #include <Events.h>
  28. #endif
  29.  
  30. #ifndef __OPENTRANSPORT__
  31. #include <OpenTransport.h>
  32. #endif
  33.  
  34. #ifndef __OPENTPTINTERNET__
  35. #include <OpenTptInternet.h>
  36. #endif
  37.  
  38.  
  39. #if GENERATINGPOWERPC
  40.  
  41. #if PRAGMA_ALIGN_SUPPORTED
  42. #pragma options align=power
  43. #endif
  44.  
  45. #define kNSpMaxPlayerNameLen        31
  46. #define kNSpMaxGroupNameLen            31
  47. #define kNSpMaxPasswordLen            31
  48. #define kNSpMaxGameNameLen            31
  49. #define kNSpMaxDefinitionStringLen    255
  50.  
  51.  
  52. /* NetSprocket basic types */
  53. typedef    struct NSpGamePrivate        *NSpGameReference;
  54. typedef    struct NSpProtocolPrivate    *NSpProtocolReference;
  55. typedef    struct NSpListPrivate        *NSpProtocolListReference;
  56. typedef struct NSPAddressPrivate    *NSpAddressReference;
  57. typedef SInt32                        NSpEventCode;
  58. typedef    SInt32                        NSpGameID;
  59. typedef    SInt32                        NSpPlayerID;
  60. typedef NSpPlayerID                    NSpGroupID;
  61. typedef UInt32                        NSpPlayerType;
  62. typedef SInt32                        NSpFlags;
  63.  
  64. /* Individual player info */
  65. typedef struct NSpPlayerInfo
  66. {
  67.     NSpPlayerID        id;
  68.     NSpPlayerType    type;
  69.     Str31            name;
  70.     UInt32            groupCount;
  71.     NSpGroupID        groups[kVariableLengthArray];
  72. } NSpPlayerInfo, *NSpPlayerInfoPtr;
  73.  
  74.     
  75. /* list of all players */
  76. typedef struct NSpPlayerEnumeration
  77. {
  78.     UInt32                count;
  79.     NSpPlayerInfoPtr    playerInfo[kVariableLengthArray];
  80. } NSpPlayerEnumeration, *NSpPlayerEnumerationPtr;
  81.  
  82.  
  83. /* Individual group info */
  84. typedef struct NSpGroupInfo
  85. {
  86.     NSpGroupID    id;
  87.     UInt32        playerCount;
  88.     NSpPlayerID    players[kVariableLengthArray];
  89. } NSpGroupInfo, *NSpGroupInfoPtr;
  90.  
  91.  
  92. /* List of all groups */
  93. typedef struct NSpGroupEnumeration
  94. {
  95.     UInt32            count;
  96.     NSpGroupInfoPtr    groups[kVariableLengthArray];
  97. } NSpGroupEnumeration, *NSpGroupEnumerationPtr;
  98.  
  99. /* Topology types */
  100. typedef UInt32 NSpTopology;
  101. enum
  102. {
  103.     kNSpClientServer =     0x00000001
  104. };
  105.  
  106. /* Game information */
  107. typedef struct NSpGameInfo
  108. {
  109.     UInt32        maxPlayers;
  110.     UInt32        currentPlayers;
  111.     UInt32        currentGroups;
  112.     NSpTopology    topology;
  113.     UInt32        reserved;
  114.     Str31        name;
  115.     Str31        password;
  116. } NSpGameInfo;
  117.     
  118.     
  119. /* Structure used for sending and receiving network messages */
  120. typedef struct NSpMessageHeader
  121. {
  122.     UInt32        version;    /* Used by NetSprocket.  Don't touch this */
  123.     SInt32        what;        /* The kind of message (e.g. player joined) */
  124.     NSpPlayerID    from;        /* ID of the sender */
  125.     NSpPlayerID    to;            /* (player or group) id of the intended recipient */
  126.     UInt32        id;            /* Unique ID for this message & (from) player */
  127.     UInt32        when;        /* Timestamp for the message */
  128.     UInt32        messageLen;    /* Bytes of data in the entire message (including the header) */
  129. } NSpMessageHeader;
  130.  
  131.  
  132. /* NetSprocket-defined message structures */
  133.  
  134. typedef struct NSpErrorMessage
  135. {
  136.     NSpMessageHeader    header;
  137.     OSStatus            error;
  138. } NSpErrorMessage;
  139.  
  140.  
  141. typedef struct NSpJoinRequestMessage
  142. {
  143.     NSpMessageHeader    header;
  144.     Str31                name;
  145.     Str31                password;
  146.     UInt32                type;
  147.     UInt32                customDataLen;
  148.     UInt8                customData[kVariableLengthArray];
  149. } NSpJoinRequestMessage;
  150.  
  151.  
  152. typedef struct NSpJoinApprovedMessage
  153. {
  154.     NSpMessageHeader    header;
  155. } NSpJoinApprovedMessage;
  156.  
  157.  
  158. typedef struct NSpJoinDeniedMessage
  159. {
  160.     NSpMessageHeader    header;
  161.     Str255                reason;
  162. } NSpJoinDeniedMessage;
  163.  
  164.  
  165. typedef struct NSpPlayerJoinedMessage
  166. {
  167.     NSpMessageHeader    header;
  168.     UInt32                playerCount;
  169.     NSpPlayerInfo            playerInfo;    
  170. } NSpPlayerJoinedMessage;
  171.  
  172.  
  173. typedef struct NSpPlayerLeftMessage
  174. {
  175.     NSpMessageHeader    header;
  176.     UInt32                playerCount;
  177.     NSpPlayerID            playerID;    
  178. } NSpPlayerLeftMessage;
  179.  
  180. typedef struct NSpHostChangedMessage
  181. {
  182.     NSpMessageHeader    header;
  183.     NSpPlayerID            newHost;
  184. } NSpHostChangedMessage;
  185.  
  186.  
  187. typedef struct NSpGameTerminatedMessage
  188. {
  189.     NSpMessageHeader    header;
  190. } NSpGameTerminatedMessage;
  191.  
  192.  
  193. /* Different kinds of messages.  These can NOT be bitwise ORed together */
  194. enum
  195. {
  196.     kNSpSendFlag_Junk =         0x00100000,        /* will be sent (try once) when there is nothing else pending */
  197.     kNSpSendFlag_Normal =         0x00200000,        /* will be sent immediately (try once) */
  198.     kNSpSendFlag_Registered =     0x00400000        /* will be sent immediately (guaranteed, in order) */
  199. };
  200.  
  201.  
  202. /* Options for message delivery.  These can be bitwise ORed together with each other,
  203.         as well as with ONE of the above */
  204. enum 
  205. {
  206.     kNSpSendFlag_FailIfPipeFull =     0x00000001,
  207.     kNSpSendFlag_SelfSend =         0x00000002,
  208.     kNSpSendFlag_Blocking =         0x00000004
  209. };
  210.  
  211.  
  212. /* Options for Hosting Joining, and Deleting games */
  213. enum
  214. {
  215.     kNSpGameFlag_DontAdvertise            =    0x00000001,
  216.     kNSpGameFlag_ForceTerminateGame     =     0x00000002
  217. };
  218.  
  219. /* Message "what" types */
  220. /* Apple reserves all negative "what" values (anything with bit 32 set) */ 
  221. enum 
  222. {
  223.     kNSpSystemMessagePrefix = 0x80000000,
  224.     kNSpError =                 kNSpSystemMessagePrefix | 0x7FFFFFFF,
  225.     kNSpJoinRequest =         kNSpSystemMessagePrefix | 0x00000001,
  226.     kNSpJoinApproved =         kNSpSystemMessagePrefix | 0x00000002,
  227.     kNSpJoinDenied =         kNSpSystemMessagePrefix | 0x00000003,
  228.     kNSpPlayerJoined =         kNSpSystemMessagePrefix | 0x00000004,
  229.     kNSpPlayerLeft =         kNSpSystemMessagePrefix | 0x00000005,
  230.     kNSpHostChanged =         kNSpSystemMessagePrefix | 0x00000006,
  231.     kNSpGameTerminated=     kNSpSystemMessagePrefix | 0x00000007
  232. };
  233.  
  234.  
  235. /* Special TPlayerIDs  for sending messages */
  236. enum
  237. {
  238.     kNSpAllPlayers =     0x00000000,
  239.     kNSpHostOnly =        0xFFFFFFFF
  240. };
  241.     
  242.  
  243. #ifdef __cplusplus
  244. extern "C" {
  245. #endif
  246.  
  247. /************************  Initialization  ************************/
  248.  
  249. OSStatus NSpInitialize(
  250.     UInt32                         inStandardMessageSize, 
  251.     UInt32                         inBufferSize, 
  252.     UInt32                         inQElements, 
  253.     NSpGameID                     inGameID, 
  254.     UInt32                         inTimeout);
  255.  
  256.  
  257. /**************************  Protocols  **************************/
  258.  
  259. /* Programmatic protocol routines */
  260. OSStatus NSpProtocol_New(
  261.     const char*                 inDefinitionString, 
  262.     NSpProtocolReference*        outReference);
  263.  
  264. void NSpProtocol_Dispose(
  265.     NSpProtocolReference         inProtocolRef);
  266.  
  267. OSStatus NSpProtocol_ExtractDefinitionString(
  268.     NSpProtocolReference         inProtocolRef, 
  269.     char*                        outDefinitionString);
  270.  
  271.  
  272. /* Protocol list routines */
  273. OSStatus NSpProtocolList_New(
  274.     NSpProtocolReference         inProtocolRef,
  275.     NSpProtocolListReference*    outList);
  276.  
  277. void NSpProtocolList_Dispose(
  278.     NSpProtocolListReference     inProtocolList);
  279.  
  280. OSStatus NSpProtocolList_Append(
  281.     NSpProtocolListReference     inProtocolList,
  282.     NSpProtocolReference         inProtocolRef);
  283.  
  284. OSStatus NSpProtocolList_Remove(
  285.     NSpProtocolListReference     inProtocolList, 
  286.     NSpProtocolReference         inProtocolRef);
  287.  
  288. OSStatus NSpProtocolList_RemoveIndexed(
  289.     NSpProtocolListReference     inProtocolList,
  290.     UInt32                         inIndex);
  291.  
  292. UInt32 NSpProtocolList_GetCount(
  293.     NSpProtocolReference         inProtocolList);
  294.  
  295. NSpProtocolReference NSpProtocolList_GetIndexedRef(
  296.     NSpProtocolListReference     inProtocolList,
  297.     UInt32                         inIndex);
  298.  
  299.  
  300. /* Helpers */
  301. NSpProtocolReference NSpProtocol_CreateAppleTalk(
  302.     ConstStr31Param             inNBPName,
  303.     ConstStr31Param             inNBPType, 
  304.     UInt32                         inMaxRTT,
  305.     UInt32                         inMinThruput);
  306.  
  307. NSpProtocolReference NSpProtocol_CreateIP(
  308.     InetPort                     inPort,
  309.     UInt32                         inMaxRTT,
  310.     UInt32                         inMinThruput);
  311.  
  312.  
  313. /***********************  Human Interface  ************************/
  314. typedef pascal Boolean (*NSpEventProcPtr) (EventRecord* inEvent);
  315.  
  316.  
  317. NSpAddressReference NSpDoModalJoinDialog(
  318.     ConstStr31Param             inGameType, 
  319.     ConstStr255Param             inEntityListLabel,
  320.     Str31                         ioName, 
  321.     Str31                         ioPassword, 
  322.     NSpEventProcPtr             inEventProcPtr);
  323.  
  324. Boolean NSpDoModalHostDialog(
  325.     NSpProtocolListReference     ioProtocolList, 
  326.     Str31                         ioGameName, 
  327.     Str31                         ioPlayerName,
  328.     Str31                         ioPassword, 
  329.     NSpEventProcPtr             inEventProcPtr);
  330.  
  331.  
  332. /*********************  Hosting and Joining  **********************/
  333.  
  334. OSStatus NSpGame_Host(
  335.     NSpGameReference*            outGame, 
  336.     NSpProtocolListReference     inProtocolList, 
  337.     UInt32                         inMaxPlayers, 
  338.     ConstStr31Param             inGameName, 
  339.     ConstStr31Param             inPassword,
  340.     ConstStr31Param             inPlayerName, 
  341.     NSpPlayerType                 inPlayerType, 
  342.     NSpTopology                 inTopology,
  343.     NSpFlags                     inFlags);
  344.  
  345. OSStatus NSpGame_Join(
  346.     NSpGameReference*            outGame, 
  347.     NSpAddressReference         inAddress, 
  348.     ConstStr31Param             inName,
  349.     ConstStr31Param             inPassword,
  350.     NSpPlayerType                 inType, 
  351.     void*                        inCustomData,
  352.     UInt32                         inCustomDataLen,  
  353.     NSpFlags                     inFlags);
  354.  
  355. OSStatus NSpGame_EnableAdvertising(
  356.     NSpGameReference             inGame, 
  357.     NSpProtocolReference         inProtocol, 
  358.     Boolean                     inEnable);
  359.  
  360. OSStatus NSpGame_Dispose(
  361.     NSpGameReference             inGame, 
  362.     NSpFlags                     inFlags);
  363.  
  364.  
  365. /**************************  Messaging  **************************/
  366.  
  367. OSStatus NSpMessage_Send(
  368.     NSpGameReference             inGame, 
  369.     NSpMessageHeader*            inMessage, 
  370.     NSpFlags                     inFlags);
  371.  
  372. NSpMessageHeader *NSpMessage_Get(
  373.     NSpGameReference             inGame);
  374.  
  375. void NSpMessage_Release(
  376.     NSpGameReference             inGame, 
  377.     NSpMessageHeader*            inMessage);
  378.  
  379. /* Helpers */
  380. OSStatus NSpMessage_SendTo(
  381.     NSpGameReference             inGame,
  382.     NSpPlayerID                    inTo,
  383.     SInt32                        inWhat, 
  384.     void*                        inData,
  385.     UInt32                        inDataLen, 
  386.     NSpFlags                     inFlags);
  387.     
  388.  
  389. /*********************  Player Information  **********************/
  390.  
  391. NSpPlayerID NSpPlayer_GetMyID(
  392.     NSpGameReference             inGame);
  393.  
  394. OSStatus NSpPlayer_GetInfo(
  395.     NSpGameReference             inGame, 
  396.     NSpPlayerID                 inPlayerID, 
  397.     NSpPlayerInfoPtr*            outInfo);
  398.  
  399. void NSpPlayer_ReleaseInfo(
  400.     NSpGameReference             inGame, 
  401.     NSpPlayerInfoPtr             inInfo);
  402.  
  403. OSStatus NSpPlayer_GetEnumeration(
  404.     NSpGameReference             inGame, 
  405.     NSpPlayerEnumerationPtr*    outPlayers);
  406.  
  407. void NSpPlayer_ReleaseEnumeration(
  408.     NSpGameReference             inGame, 
  409.     NSpPlayerEnumerationPtr     inPlayers);
  410.  
  411. UInt32 NSpPlayer_GetRoundTripTime(
  412.     NSpGameReference             inGame, 
  413.     NSpPlayerID                 inPlayer); 
  414.  
  415. UInt32 NSpPlayer_GetThruput(
  416.     NSpGameReference             inGame, 
  417.     NSpPlayerID                 inPlayer); 
  418.  
  419.  
  420. /*********************  Group Management  **********************/
  421.  
  422. OSStatus NSpGroup_New(
  423.     NSpGameReference             inGame, 
  424.     NSpGroupID*                    outGroupID);
  425.  
  426. OSStatus NSpGroup_Dispose(
  427.     NSpGameReference             inGame, 
  428.     NSpGroupID                     inGroupID);
  429.  
  430. OSStatus NSpGroup_AddPlayer(
  431.     NSpGameReference             inGame, 
  432.     NSpGroupID                     inGroupID, 
  433.     NSpPlayerID                 inPlayerID);
  434.  
  435. OSStatus NSpGroup_RemovePlayer(
  436.     NSpGameReference             inGame, 
  437.     NSpGroupID                     inGroupID,
  438.     NSpPlayerID                 inPlayerID);
  439.  
  440. OSStatus NSpGroup_GetInfo(
  441.     NSpGameReference             inGame, 
  442.     NSpGroupID                     inGroupID, 
  443.     NSpGroupInfoPtr*            outInfo);
  444.  
  445. void NSpGroup_ReleaseInfo(
  446.     NSpGameReference             inGame, 
  447.     NSpGroupInfoPtr             inInfo);
  448.  
  449. OSStatus NSpGroup_GetEnumeration(
  450.     NSpGameReference             inGame, 
  451.     NSpGroupEnumerationPtr*        outGroups);
  452.  
  453. void NSpGroup_ReleaseEnumeration(
  454.     NSpGameReference             inGame, 
  455.     NSpGroupEnumerationPtr         inGroups);
  456.  
  457.  
  458. /**************************  Utilities  ***************************/
  459.  
  460. void NSpClearMessageHeader(
  461.     NSpMessageHeader*            inMessage);
  462.  
  463. UInt32 NSpGetCurrentTimeStamp(
  464.     NSpGameReference             inGame);
  465.  
  466. NSpAddressReference    NSpConvertOTAddrToAddressReference(
  467.     OTAddress*                    inAddress);
  468.  
  469. OTAddress *NSpConvertAddressReferenceToOTAddr(
  470.     NSpAddressReference         inAddress);
  471.  
  472. void NSpReleaseAddressReference(
  473.     NSpAddressReference         inAddress);
  474.  
  475.  
  476. /************************ Advanced/Async routines ****************/
  477.  
  478. typedef pascal void (*NSpCallbackProcPtr)(
  479.     NSpGameReference             inGame, 
  480.     void*                         inContext, 
  481.     NSpEventCode                 inCode, 
  482.     OSStatus                     inStatus, 
  483.     void*                         inCookie);
  484.  
  485. OSStatus NSpInstallCallbackHandler(
  486.     NSpCallbackProcPtr             inHandler, 
  487.     void*                        inContext);
  488.  
  489.  
  490. typedef pascal Boolean (*NSpJoinRequestHandlerProcPtr)(
  491.     NSpGameReference             inGame, 
  492.     NSpJoinRequestMessage*        inMessage, 
  493.     void*                         inContext,
  494.     Str255                        outReason);
  495.  
  496. OSStatus NSpInstallJoinRequestHandler(
  497.     NSpJoinRequestHandlerProcPtr inHandler, 
  498.     void*                        inContext);
  499.  
  500.  
  501. typedef pascal Boolean (*NSpMessageHandlerProcPtr)(
  502.     NSpGameReference             inGame, 
  503.     NSpMessageHeader*            inMessage, 
  504.     void*                         inContext);
  505.  
  506. OSStatus NSpInstallAsyncMessageHandler(
  507.     NSpMessageHandlerProcPtr     inHandler, 
  508.     void*                        inContext);
  509.  
  510.  
  511.  
  512.  
  513. #ifdef __cplusplus
  514. }
  515. #endif
  516.  
  517. /* NetSprocket Error Codes */
  518. enum
  519. {
  520.     kNSpInitializationFailedErr         = -30360,
  521.     kNSpAlreadyInitializedErr             = -30361,
  522.     kNSpTopologyNotSupportedErr         = -30362,
  523.     kNSpPipeFullErr                         = -30364,
  524.     kNSpHostFailedErr                     = -30365,
  525.     kNSpProtocolNotAvailableErr         = -30366,
  526.     kNSpInvalidGameRefErr                 = -30367,
  527.     kNSpInvalidParameterErr             = -30369,
  528.     kNSpOTNotPresentErr                 = -30370,
  529.     kNSpOTVersionTooOldErr                = -30371,
  530.     kNSpMemAllocationErr                 = -30373,
  531.     kNSpAlreadyAdvertisingErr             = -30374,
  532.     kNSpNotAdvertisingErr                 = -30376,
  533.     kNSpInvalidAddressErr                 = -30377,
  534.     kNSpFreeQExhaustedErr                = -30378,
  535.     kNSpRemovePlayerFailedErr            = -30379,
  536.     kNSpAddressInUseErr                    = -30380,
  537.     kNSpFeatureNotImplementedErr        = -30381,
  538.     kNSpNameRequiredErr                 = -30382,
  539.     kNSpInvalidPlayerIDErr                 = -30383,
  540.     kNSpInvalidGroupIDErr                 = -30384,
  541.     kNSpNoPlayersErr                     = -30385,
  542.     kNSpNoGroupsErr                     = -30386,
  543.     kNSpNoHostVolunteersErr             = -30387,
  544.     kNSpCreateGroupFailedErr             = -30388,
  545.     kNSpAddPlayerFailedErr                 = -30389,
  546.     kNSpInvalidDefinitionErr            = -30390,
  547.     kNSpInvalidProtocolRefErr            = -30391,
  548.     kNSpInvalidProtocolListErr            = -30392,
  549.     kNSpTimeoutErr                        = -30393,
  550.     kNSpGameTerminatedErr                = -30394,
  551.     kNSpConnectFailedErr                = -30395,
  552.     kNSpSendFailedErr                    = -30396,
  553.     kNSpJoinFailedErr                    = -30399
  554. };
  555.  
  556.  
  557.  
  558. #if PRAGMA_ALIGN_SUPPORTED
  559. #pragma options align=reset
  560. #endif
  561.  
  562. #endif /* GENERATINGPOWERPC */
  563. #endif /* __NETSPROCKET__ */
  564.